docs: how to update the OroCommerce piece and the fork - #9

Merges instructions/install-orocommerce-piece-en.md (kept outside this
repo) into docs/FORK-UPDATE.md. That file was §3/§5/§6 reorganised for
someone performing an install rather than reading about the fork; it is
not added here as a second file, and nothing it describes is now
described in two places.

Moved into §5:

- a "which path applies" decision table (cloud lane vs customer lane) at
  the top, so a reader sorts themselves before reading preconditions. It
  routes only; mechanism detail stays in §3 instead of being restated.
- preconditions as a numbered list, deduplicated against the table, with
  the uncommitted-insert 401 folded into the API-key item.
- the install curl, unchanged in substance, plus the note that name and
  version come from the form fields and not from the tarball.
- "listing what is installed", replacing the incorrect claim that
  GET /api/v1/pieces/<name> lists installed versions. It returns a single
  object and CE has no per-piece versions route, so use the registry
  route with release and edition and filter by name. Both params are
  mandatory: RegistryPiecesRequestQuery marks neither optional, in
  packages/core/shared/src/lib/automation/pieces/dto/piece-requests.ts.
  Its source-read, not-run-live caveat is kept.

Moved into §6, the signature-check paragraph, and a failure-modes table
at the end collecting the symptoms previously scattered through §5 and
§6 prose.

The five fixes:

1. §2 already named 1.0.0 as the current release, so there was nothing
   to correct there. The record is verified against the built artifact:
   67144 bytes, sha256 ced1e853f15717b11e8c6282d619c3e0443780c7035c4ced
   69fbc35915a0663c, inner package/src/index.js sha256 11ad8876e985a488
   6be58645474ff5a442eefe4317611ae33feed922faef6cff, and exactly eight
   files. The branch it was built on is deliberately not named.

2. New §6 "signDeliveries trap". Re-pinning echoes the whole trigger
   object back, which carries an old explicit false forward. Verified in
   the piece webhook topic trigger. onEnable suppresses the secret only
   on a strict === false, so a missing key signs:

     const secret =
       context.propsValue.signDeliveries === false
         ? undefined
         : randomBytes(32).toString('hex');

   and run() keys off the stored secret rather than the prop, so the
   re-pinned flow passes deliveries through unverified:

     const webhookInfo = await context.store.get('webhookInfo');
     const secret = webhookInfo?.secret;
     if (secret === undefined || secret === null) {
       return [context.payload.body];
     }

   The section says a migration has to decide whether to force the key
   rather than preserve it.

3. The post-re-pin check filters by flow id, notification_url LIKE
   '%<flowId>%', not by full URL: if AP_FRONTEND_URL has changed, a
   URL-scoped query returns exactly one row whether or not a stale
   registration survives under the old URL, which is a false pass.

4. The Oro column is named explicitly as notification_url throughout §6.

5. No statement of current branch state imported. §1's check command,
   whose output the reader interprets, still handles that.

One existing caveat was corrected rather than preserved: "what Oro sends
on the wire is not captured yet" is false, the headers having been
captured live on 3 Sep 2026. Oro sends Webhook-Signature, 64 hex, and
Webhook-Signature-Algorithm HMAC-SHA256; the piece reads only
webhook-signature, its sole header read, and ignores the algorithm
header, the string "algorithm" occurring nowhere in the package. Every
other caveat is kept.

Also checked against the repo, with no mismatches found: npm pack emits
activepieces-piece-orocommerce-<version>.tgz, now noted in §4 step 4
beside the head-<sha>-<version>.tgz rename; the Dockerfile.oro prune
exemption list is slack, square, facebook-leads, intercom, orocommerce;
.env.oro.example sets AP_DEV_PIECES, AP_PIECES_SOURCE and
AP_PIECES_SYNC_MODE as documented; PieceScope has only PLATFORM; and the
piece exports 11 actions and 1 trigger.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>